Skip to main content

RunManagementController

The RunManagementController provides comprehensive management of SWMM simulation runs with full CRUD operations and enhanced data models.

Overview​

This controller manages the complete lifecycle of SWMM simulation runs, including creation, monitoring, status updates, and deletion. It uses normalized DTOs and provides enhanced functionality compared to the basic ScenarioController.

Data Sources​

  • Azure Table Storage:
    • Runs table for run metadata and status
    • Inputs table for scenario and input data
  • Configuration: Dependency injection for table service client
  • No Blob Storage: Focuses on metadata management

Endpoints​

GET /api/runmanagement​

Retrieves all simulation runs across all scenarios.

Response:

  • 200 OK: Returns list of RunDto objects
  • 500 Internal Server Error: Database error

Data Flow:

GET /api/runmanagement/{scenarioId}/{runId}​

Retrieves a specific run by scenario and run ID.

Path Parameters:

  • scenarioId (string): Scenario identifier
  • runId (string): Run identifier

Response:

  • 200 OK: Returns RunDto object
  • 404 Not Found: Run not found
  • 500 Internal Server Error: Database error

GET /api/runmanagement/status/{status}​

Retrieves runs filtered by status.

Path Parameters:

  • status (string): Run status to filter by

Response:

  • 200 OK: Returns filtered list of RunDto objects
  • 500 Internal Server Error: Database error

Supported Statuses:

  • RUNNING
  • COMPLETED
  • FAILED
  • PENDING
  • CANCELLED

POST /api/runmanagement​

Creates a new simulation run.

Request Body:

{
  "scenarioId": "string",
  "startTime": "2023-11-16T00:00:00-05:00",
  "endTime": "2023-11-16T23:59:59-05:00",
  "reportingTimeStep": 15,
  "inputFile": "scenario.inp"
}

Response:

  • 201 Created: Returns created RunDto object
  • 400 Bad Request: Validation error
  • 500 Internal Server Error: Database error

Data Flow:

PUT /api/runmanagement/{scenarioId}/{runId}/status​

Updates the status of a specific run.

Path Parameters:

  • scenarioId (string): Scenario identifier
  • runId (string): Run identifier

Request Body:

"COMPLETED"

Response:

  • 200 OK: Returns updated RunDto object
  • 404 Not Found: Run not found
  • 500 Internal Server Error: Database error

DELETE /api/runmanagement/{scenarioId}/{runId}​

Deletes a specific run.

Path Parameters:

  • scenarioId (string): Scenario identifier
  • runId (string): Run identifier

Response:

  • 204 No Content: Run deleted successfully
  • 404 Not Found: Run not found
  • 500 Internal Server Error: Database error

GET /api/runmanagement/{scenarioId}/latest-completed​

Retrieves the most recent completed run for a scenario.

Path Parameters:

  • scenarioId (string): Scenario identifier

Response:

  • 200 OK: Returns RunDto object
  • 404 Not Found: No completed runs found
  • 500 Internal Server Error: Database error

GET /api/runmanagement/statistics​

Retrieves run statistics across all scenarios.

Response:

  • 200 OK: Returns statistics object
  • 500 Internal Server Error: Database error

Statistics Response:

{
  "totalRuns": 150,
  "completedRuns": 120,
  "failedRuns": 15,
  "runningRuns": 5,
  "pendingRuns": 10,
  "averageRunTime": "00:45:30",
  "scenariosWithRuns": 8
}

Data Models​

RunDto​

public class RunDto
{
    public string ScenarioId { get; set; }
    public string RunId { get; set; }
    public string Status { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime EndTime { get; set; }
    public int ReportingTimeStep { get; set; }
    public string InputFile { get; set; }
    public double? Flow { get; set; }
    public double? Flooding { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? CompletedAt { get; set; }
}

RunSimulationRequest​

public class RunSimulationRequest
{
    public string ScenarioId { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime EndTime { get; set; }
    public int ReportingTimeStep { get; set; }
    public string InputFile { get; set; }
}

Azure Storage Details​

Table Storage Schema​

Runs Table:

  • PartitionKey: {scenarioId}
  • RowKey: {runId}
  • Properties: Status, StartTime, EndTime, ReportingTimeStep, InputFile, Flow, Flooding, CreatedAt, CompletedAt

Inputs Table:

  • PartitionKey: {scenarioId}
  • RowKey: {inputId}
  • Properties: Input data for scenarios

Error Handling​

  • Validation Errors: Returns 400 with validation details
  • Not Found: Returns 404 for missing entities
  • Database Errors: Returns 500 with error logging
  • Concurrent Access: Handles ETag conflicts

Performance Considerations​

  • Async Operations: All database operations are async
  • Pagination: Supports large result sets
  • Indexing: Optimized for scenario and status queries
  • Caching: No built-in caching (consider for frequently accessed data)

Dependencies​

  • Azure.Data.Tables
  • SwmmModels.DTOs
  • SwmmModels.Requests
  • SwmmModels.Validators
  • SwmmModels.Enums

Workflow Integration​

Run Lifecycle​

Status Transitions​

  • PENDING: Run created, waiting to start
  • RUNNING: Simulation in progress
  • COMPLETED: Simulation finished successfully
  • FAILED: Simulation encountered errors
  • CANCELLED: Run was cancelled by user

Monitoring and Logging​

  • Request Logging: All operations are logged
  • Error Tracking: Detailed error information
  • Performance Metrics: Run statistics and timing
  • Audit Trail: Complete history of status changes

Security Considerations​

  • Input Validation: All inputs are validated
  • Authorization: Requires proper authentication
  • Data Sanitization: Prevents injection attacks
  • Access Control: Scenario-based access control

Usage Examples​

Create New Run:

POST /api/runmanagement
{
  "scenarioId": "scenario1",
  "startTime": "2023-11-16T00:00:00-05:00",
  "endTime": "2023-11-16T23:59:59-05:00",
  "reportingTimeStep": 15,
  "inputFile": "scenario1.inp"
}

Update Run Status:

PUT /api/runmanagement/scenario1/run123/status
"COMPLETED"

Get Run Statistics:

GET /api/runmanagement/statistics